vFire has two Application Programming Interfaces (or APIs), which enable you to develop programs that automate many common vFire transactions. This section of the documentation deals with the Classic API. For more information on the RESTful Alemba API, introduced in 9.7, see here.
The API provides transactions to create, update, forward, close, add notes and retrieve calls. Messaging transactions are provided to email the call’s forum.
Timesheet transactions are provided for updating existing calls.
Availability transactions are provided to find outages linked to existing calls.
When calls are created, there is an option to pass a list of CMDB Items against which an outage can be created. If possible, the API will create an outage against the specified items. If the transaction is unable to create an outage against the specified item, it may return an error.
CallCreate Transaction
The CallCreate transaction can be used to log a call. A call template can be specified to log a call.
Input Parameters: CallCreateRequest
|
Argument |
Type |
Mandatory |
Default |
Description |
|---|---|---|---|---|
|
sID |
String |
No. See Transaction Login. |
“” |
Analyst’s current Session ID |
|
sLoginUserID |
String |
No. See Transaction Login. |
“” |
Analyst’s Login ID |
|
sLoginPassword |
String |
No. See Transaction Login. |
“” |
Analyst’s Password |
|
sDatabase |
String |
No. See Transaction Login. |
“” |
Name of the vFire system for logging in. |
|
lEntityRef |
Lookup Field |
Ignored |
- |
Ignored on Create |
|
lTemplateRef |
Lookup Field |
No |
0 |
Call Template used to log the call |
|
sCallRef |
String |
No |
“” |
Call Ref on the call |
|
lCustomer |
Lookup Field |
No |
0 |
User on the call |
|
lLocation |
Lookup Field |
No |
0 |
Location on the call |
|
lOrganization |
Lookup Field |
No |
0 |
Organization on the call |
|
lConfigItem |
Lookup Field |
No |
0 |
Config Item on the call |
|
lFwdOfficer |
Lookup Field |
No |
0 |
Analyst to which this call will be assigned |
|
lService |
Lookup Field |
No |
0 |
Service on the call |
|
lServiceAction |
Lookup Field |
No |
0 |
Service Action on the call |
|
lServiceBundle |
Lookup Field |
No |
0 |
Service Bundle on the call |
|
lImpact |
Lookup Field |
No |
0 |
Call Impact |
|
lPriority |
Lookup Field |
No |
0 |
Call Priority |
|
lUrgency |
Lookup Field |
No |
0 |
Call Urgency |
|
lFwdGroup |
Lookup Field |
No |
0 |
Group to which this call will be assigned |
|
lIPKStatus |
Lookup Field |
No |
Analyst’s default IPK status |
IPK status applied to the call |
|
lIPKStream |
Lookup Field |
No |
Analyst’s default IPK stream |
IPK stream applied to the call |
|
sActionDescription |
String |
No |
“” |
Action & Solution history entry |
|
sProblemDescription |
String |
No |
“” |
Call Description |
|
yPortal |
|
No |
N |
Display this Action & Solution history entry on Self Service Portal? Values:
|
|
lType |
Lookup Field |
No |
0 |
Call Issue Type |
|
dActionEnd |
Date/Time |
No |
Now |
Action End Date |
|
dActionStart |
Date/Time |
No |
Now |
Action Start Date |
|
lActionType |
Lookup Field |
No |
0 |
Action Type corresponding to the Action & Solution history entry |
|
nEstimatedHours |
Integer |
No |
Uses the difference between the Action Start and Action End |
Action & Solution recorded time spent |
|
nEstimatedMins |
Integer |
No |
Uses the difference between the Action Start and Action End |
Action & Solution recorded time spent |
|
nExpenses |
Integer |
No |
0 |
Action & Solution recorded expenditure |
|
bCreateOutage |
Boolean |
No |
False |
Create an outage against the specified CMDB item or Service and link it to this call. Values:
|
|
dOutageEnd |
Date/Time |
No |
(NULL) |
Outage end date; if entered, this date must be in the past. Outage end date is entered in the logging analyst’s time zone. |
|
dOutageStart |
Date/Time |
No |
Now – if Create Outage was selected |
Outage start date. Outage start date is entered in the logging analyst’s time zone. |
|
lOutageType |
Lookup Field |
No |
Unspecified Unplanned |
Outage Type. This must be an unplanned Outage Type. |
|
sOutageDesc |
String |
No |
“” |
Description of the created outage |
|
sOutageItemList |
String |
No |
“” |
List of CMDB items or Services linked to the call (or dependent on these CI) against which to create the outage. These outages will be linked to the call. |
|
lCallStatus |
Lookup Field |
No |
0 |
Call Status |
|
lPartition |
Lookup Field |
No |
Analyst’s default partition |
Call Partition. Ignored if a call template is specified, to which the partition on the template is used. |
|
lSecurity |
Lookup Field |
No |
0 |
Security Profile applied to the Action & Solution history entry. |
|
bSendEmail |
Boolean |
No |
False |
Send an email to the assigned analyst/group regarding this call. Values:
|
|
bSendPager |
Boolean |
No |
False |
Send a pager message to the assigned analyst/group regarding this call. Values:
|
|
aCustomParameters |
Array |
No |
“” |
Return Values: CallResponse
|
Argument |
Type |
Description |
|---|---|---|
|
nEntityRef |
Integer |
New Call Number |
|
String |
Error/Warning Message |
|
|
Ret |
Error/Warning Number |
CallUpdate Transaction
The CallUpdate transaction can be used to update and defer a call.
Input Parameters: CallUpdateRequest
CallUpdateRequest
|
Argument |
Type |
Mandatory |
Default |
Description |
|---|---|---|---|---|
|
sID |
String |
No. See Transaction Login. |
“” |
Analyst’s current Session ID |
|
sLoginUserID |
String |
No. See Transaction Login. |
“” |
Analyst’s Login ID |
|
sLoginPassword |
String |
No. See Transaction Login. |
“” |
Analyst’s Password |
|
sDatabase |
String |
No. See Transaction Login. |
“” |
Name of the vFire system for logging in. |
|
lEntityRef |
Lookup Field |
Yes |
- |
Call to update |
|
lTemplateRef |
Lookup Field |
No |
(As is) |
Call Template used to log the call |
|
sCallRef |
String |
No |
(As is) |
Call Ref on the call |
|
lCustomer |
Lookup Field |
No |
(As is) |
User on the call |
|
lLocation |
Lookup Field |
No |
(As is) |
Location on the call |
|
lOrganization |
Lookup Field |
No |
(As is) |
Organization on the call |
|
lConfigItem |
Lookup Field |
No |
(As is) |
Config Item on the call |
|
lFwdOfficer |
Lookup Field |
No |
(As is) |
Analyst to which this call will be assigned |
|
lService |
Lookup Field |
No |
(As is) |
Service on the call |
|
lServiceAction |
Lookup Field |
No |
(As is) |
Service Action on the call |
|
lServiceBundle |
Lookup Field |
No |
(As is) |
Service Bundle on the call |
|
lImpact |
Lookup Field |
No |
(As is) |
Call Impact |
|
lPriority |
Lookup Field |
No |
(As is) |
Call Priority |
|
lUrgency |
Lookup Field |
No |
(As is) |
Call Urgency |
|
lFwdGroup |
Lookup Field |
No |
(As is) |
Group to which this call will be assigned |
|
lIPKStatus |
Lookup Field |
No |
(As is) |
IPK status applied to the call |
|
lIPKStream |
Lookup Field |
No |
(As is) |
IPK stream applied to the call |
|
sActionDescription |
String |
No |
(As is) |
Action & Solution history entry |
|
sProblemDescription |
String |
No |
(As is) |
Call Description |
|
yPortal |
Yes/No |
No |
(As is) |
Display this Action & Solution history entry on Self Service Portal? Values:
|
|
lType |
Lookup Field |
No |
|
Call Issue Type |
|
dActionEnd |
Date/Time |
No |
Now |
Action End Date |
|
dActionStart |
Date/Time |
No |
Now |
Action Start Date |
|
lActionType |
Lookup Field |
No |
0 |
Action Type corresponding to the Action & Solution history entry |
|
nEstimatedHours |
Integer |
No |
Uses the difference between the Action Start and Action End |
Action & Solution recorded time spent |
|
nEstimatedMins |
Integer |
No |
Uses the difference between the Action Start and Action End |
Action & Solution recorded time spent |
|
nExpenses |
Integer |
No |
0 |
Action & Solution recorded expenditure |
|
bCreateOutage |
Boolean |
No |
False |
Create an outage against the specified CMDB item or Service and link it to this call. Values:
|
|
dOutageEnd |
Date/Time |
No |
(NULL) |
Outage end date; if entered, this date must be in the past. Outage end date is entered in the logging analyst’s time zone. |
|
dOutageStart |
Date/Time |
No |
Now – if Create Outage was selected |
Outage start date. Outage start date is entered in the logging analyst’s time zone. |
|
lOutageType |
Lookup Field |
No |
Unspecified Unplanned |
Outage Type. This must be an unplanned Outage Type. |
|
sOutageDesc |
String |
No |
“” |
Description of the created outage |
|
sOutageItemList |
String |
No |
“” |
List of CMDB items or Services linked to the call (or dependent on these CI) against which to create the outage. These outages will be linked to the call. |
|
lCallStatus |
Lookup Field |
No |
(As is) |
Call Status |
|
lPartition |
Lookup Field |
No |
(As is) |
Call Partition. |
|
lSecurity |
Lookup Field |
No |
0 |
Security Profile applied to the Action & Solution history entry. |
|
bSendEmail |
Boolean |
No |
False |
Send an email to the assigned analyst/group regarding this call. Values:
|
|
bSendPager |
Boolean |
No |
False |
Send a pager message to the assigned analyst/group regarding this call. Values:
|
|
aCustomParameters |
Array |
No |
“” |
Return Values: CallResponse
See CallResponse for more information.
CallRetrieve Transaction
The CallRetrieve transaction can be used to retrieve an existing call’s details without taking action on it.
Input Parameters: CallRetrieveRequest
|
Argument |
Type |
Mandatory |
Default |
Description |
|---|---|---|---|---|
|
sID |
String |
No. See Transaction Login. |
“” |
Analyst’s current Session ID |
|
sLoginUserID |
String |
No. See Transaction Login. |
“” |
Analyst’s Login ID |
|
sLoginPassword |
String |
No. See Transaction Login. |
“” |
Analyst’s Password |
|
sDatabase |
String |
No. See Transaction Login. |
“” |
Name of the vFire system for logging in. |
|
lEntityRef |
Lookup Field |
Yes |
- |
Call to retrieve |
|
aCustomParameters |
Array |
No |
“” |
Return Values: CallRetrieveResponse
|
Argument |
Type |
Description |
|---|---|---|
|
Ret |
Error/Warning Number |
|
|
String |
Error/Warning Message |
|
|
ResultSet |
DataSet |
CallForwardInternal Transaction
The CallForwardInternal transaction can be used to forward an existing call internally to an analyst or group.
Input Parameters: CallInternalRequest
|
Argument |
Type |
Mandatory |
Default |
Description |
|---|---|---|---|---|
|
sID |
String |
No. See Transaction Login. |
“” |
Analyst’s current Session ID |
|
sLoginUserID |
String |
No. See Transaction Login. |
“” |
Analyst’s Login ID |
|
sLoginPassword |
String |
No. See Transaction Login. |
“” |
Analyst’s Password |
|
sDatabase |
String |
No. See Transaction Login. |
“” |
Name of the vFire system for logging in. |
|
lEntityRef |
Lookup Field |
Yes |
- |
Number of the call in which to forward |
|
lFwdOfficer |
Lookup Field |
No |
0 |
Analyst to which the call will be assigned |
|
lFwdGroup |
Lookup Field |
No |
0 |
Group to which the call will be assigned |
|
bSendEmail |
Boolean |
No |
False |
Send an email to the assigned analyst/group regarding this call. Values: True = send an email to the assigned analyst/group False = no email is sent |
|
bSendPager |
Boolean |
No |
False |
Send a pager message to the assigned analyst/group regarding this call. Values: True = send a pager message to the assigned analyst/group False = no pager message is sent |
|
aCustomParameters |
Array |
No |
“” |
Return Values: CallResponse
See CallResponse for more information.
CallForwardExternal Transaction
The CallForwardExternal transaction can be used to forward an existing call externally.
Input Parameters: CallExternalRequest
|
Argument |
Type |
Mandatory |
Default |
Description |
|---|---|---|---|---|
|
sID |
String |
No. See Transaction Login. |
“” |
Analyst’s current Session ID |
|
sLoginUserID |
String |
No. See Transaction Login. |
“” |
Analyst’s Login ID |
|
sLoginPassword |
String |
No. See Transaction Login. |
“” |
Analyst’s Password |
|
sDatabase |
String |
No. See Transaction Login. |
“” |
Name of the vFire system for logging in. |
|
lEntityRef |
Lookup Field |
Yes |
- |
Number of the call to forward externally |
|
lFwdOfficer |
Lookup Field |
Yes |
0 |
Analyst to which the call will be assigned. Will forward the call if provided. |
|
lExternalSupplier |
Lookup Field |
No |
0 |
External supplier to which the call will be assigned. |
|
lContract |
Lookup Field |
No |
0 |
Contract to apply when forwarded externally |
|
sJobRef |
String |
No |
“” |
External Job Reference |
|
yEmailSupplier |
Yes/No |
No |
N |
Send an email to the specified External Supplier. Values: Y = send email to assigned external supplier N = do not send email to assigned external supplier |
|
bSendEmail |
Boolean |
No |
False |
Send an email to the assigned analyst. Values: Y = send email to assigned analyst N = do not send email to assigned analyst |
|
bSendPager |
Boolean |
No |
False |
Send a pager message to the assigned analyst. Values: Y = send pager message to assigned analyst N = do not send pager message to assigned analyst |
|
aCustomParameters |
Array |
No |
“” |
Return Values: CallResponse
See CallResponse for more information.
CallClose Transaction
The CallClose transaction can be used to close an existing call.
Input Parameters: CallCloseRequest
|
Argument |
Type |
Mandatory |
Default |
Description |
|---|---|---|---|---|
|
sID |
String |
No. See Transaction Login. |
“” |
Analyst’s current Session ID |
|
sLoginUserID |
String |
No. See Transaction Login. |
“” |
Analyst’s Login ID |
|
sLoginPassword |
String |
No. See Transaction Login. |
“” |
Analyst’s Password |
|
sDatabase |
String |
No. See Transaction Login. |
“” |
Name of the vFire system for logging in. |
|
lEntityRef |
Lookup Field |
Yes |
- |
Number of the call to close |
|
lReason |
Lookup Field |
No |
0 |
Reason for closing the call |
|
lCallStatus |
Lookup Field |
No |
0 |
Call Status |
|
sOneLiner |
String |
No |
“” |
One Line explanation for closing the call |
|
bCloneToKnowledgeBank |
Boolean |
Mp |
False |
Whether to create a KB entry based on this call. Values:
|
|
bEmailCustomer |
Boolean |
No |
False |
Whether to send an email to the User informing that this call is closed. Values:
|
|
aCustomParameters |
Array |
No |
“” |
Return Values: CallResponse
See CallResponse for more information.
CallFindLinkedOutage Transaction
The CallFindLinkedOutages transaction can be used to find outages linked to this call.
Input Parameters: CallFindLinkedOutageRequest
|
Argument |
Type |
Mandatory |
Default |
Description |
|---|---|---|---|---|
|
sID |
String |
No. See Transaction Login. |
“” |
Analyst’s current Session ID |
|
sLoginUserID |
String |
No. See Transaction Login. |
“” |
Analyst’s Login ID |
|
sLoginPassword |
String |
No. See Transaction Login. |
“” |
Analyst’s Password |
|
sDatabase |
String |
No. See Transaction Login. |
“” |
Name of the vFire system for logging in. |
|
lEntityRef |
Lookup Field |
Yes |
- |
Call number for which to find linked outages. |
|
aCustomParameters |
Array |
No |
“” |
Return Values: CallRetrieveResponse
See CallRetrieveResponse for more information.
CallMessageForum Transaction
The CallMessageForum transaction can be used to send an email to the forum attached to a call.
Input Parameters: CallMessageForumRequest
|
Argument |
Type |
Mandatory |
Default |
Description |
|---|---|---|---|---|
|
sID |
String |
No. See Transaction Login. |
“” |
Analyst’s current Session ID |
|
sLoginUserID |
String |
No. See Transaction Login. |
“” |
Analyst’s Login ID |
|
sLoginPassword |
String |
No. See Transaction Login. |
“” |
Analyst’s Password |
|
sDatabase |
String |
No. See Transaction Login. |
“” |
Name of the vFire system for logging in. |
|
lEntityRef |
Lookup Field |
Yes |
- |
Number of the call to which an email will be sent to forum members |
|
bForumNotLinked |
Boolean |
No |
F |
Whether to email a forum linked to the call (e.g. IPK workflow rules), or to email the forum members attached manually to the call (e.g. via call watch). Values: True = email all forum members False = email only forum members who manually watched the call |
|
aCustomParameters |
Array |
No |
“” |
Return Values: CallResponse
See CallResponse for more information.
CallTimesheetCreate Transaction
The CallTimesheetCreate transaction can be used to add a timesheet entry for a call.
Input Parameters: CallTimesheetCreateRequest
|
Argument |
Type |
Mandatory |
Default |
Description |
|---|---|---|---|---|
|
sID |
String |
No. See Transaction Login. |
“” |
Analyst’s current Session ID |
|
sLoginUserID |
String |
No. See Transaction Login. |
“” |
Analyst’s Login ID |
|
sLoginPassword |
String |
No. See Transaction Login. |
“” |
Analyst’s Password |
|
sDatabase |
String |
No. See Transaction Login. |
“” |
Name of the vFire system for logging in. |
|
lEntityRef |
Lookup Field |
Yes |
- |
Number of the call to create a timesheet entry |
|
nHistoryOrder |
Integer |
Ignored |
- |
History order. Automatically generated on create transaction. |
|
lTimesheetAction |
Lookup Field |
No |
|
Timesheet action |
|
sHistoryDesc |
String |
No |
“” |
History description |
|
dStartDate |
Date/Time |
No |
Now |
History Start Date |
|
dEndDate |
Date/Time |
No |
Now |
History End Date |
|
nExpenses |
Integer |
No |
0 |
Expenses |
|
yPortal |
Yes/No |
No |
False |
Make this history entry visible on the Self Service Portal? Values: True = history entry is visible on the Self Service Portal False = history entry not displayed on the Self Service Portal |
|
lSecurityProfile |
Lookup Field |
No |
0 |
Security Profile to apply to the timesheet entry |
|
aCustomParameters |
Array |
No |
“” |
Return Values: CallResponse
See CallResponse for more information.
CallTimesheetUpdate Transaction
The CallTimeSheetUpdate transaction can be used to update a timesheet entry for a call.
Input Parameters: CallTimesheetUpdateRequest
|
Argument |
Type |
Mandatory |
Default |
Description |
|---|---|---|---|---|
|
sID |
String |
No. See Transaction Login. |
“” |
Analyst’s current Session ID |
|
sLoginUserID |
String |
No. See Transaction Login. |
“” |
Analyst’s Login ID |
|
sLoginPassword |
String |
No. See Transaction Login. |
“” |
Analyst’s Password |
|
sDatabase |
String |
No. See Transaction Login. |
“” |
Name of the vFire system for logging in. |
|
lEntityRef |
Lookup Field |
Yes |
- |
Number of the call to create a timesheet entry |
|
nHistoryOrder |
Integer |
Yes |
- |
History order to update |
|
lTimesheetAction |
Lookup Field |
No |
(As is) |
Timesheet action |
|
sHistoryDesc |
String |
No |
(As is) |
History description |
|
dStartDate |
Date/Time |
No |
(As is) |
History Start Date |
|
dEndDate |
Date/Time |
No |
(As is) |
History End Date |
|
nExpenses |
Integer |
No |
(As is) |
Expenses |
|
yPortal |
Yes/No |
No |
(As is) |
Make this history entry visible on the Self Service Portal? Values:
|
|
lSecurityProfile |
Lookup Field |
No |
(As is) |
Security Profile to apply to the timesheet entry |
|
aCustomParameters |
Array |
No |
“” |
Return Values: CallResponse
See CallResponse for more information.
CallTimesheetDelete Transaction
The CallTimeSheetDelete transaction can be used to delete a timesheet entry for a call.
Input Parameters: CallTimesheetDeleteRequest
|
Argument |
Type |
Mandatory |
Default |
Description |
|---|---|---|---|---|
|
sID |
String |
No. See Transaction Login. |
“” |
Analyst’s current Session ID |
|
sLoginUserID |
String |
No. See Transaction Login. |
“” |
Analyst’s Login ID |
|
sLoginPassword |
String |
No. See Transaction Login. |
“” |
Analyst’s Password |
|
sDatabase |
String |
No. See Transaction Login. |
“” |
Name of the vFire system for logging in. |
|
lEntityRef |
Lookup Field |
Yes |
- |
Number of the call to create a timesheet entry |
|
nHistoryOrder |
Integer |
Yes |
- |
History order to update |
|
lTimesheetAction |
Lookup Field |
Ignored |
|
Timesheet action |
|
sHistoryDesc |
String |
Ignored |
- |
History description |
|
dStartDate |
Date/Time |
Ignored |
- |
History Start Date |
|
dEndDate |
Date/Time |
Ignored |
- |
History End Date |
|
nExpenses |
Integer |
Ignored |
- |
Expenses |
|
yPortal |
Yes/No |
Ignored |
- |
Make this history entry visible on the Self Service Portal? Values:
|
|
lSecurityProfile |
Lookup Field |
Ignored |
- |
Security Profile to apply to the timesheet entry |
|
aCustomParameters |
Array |
No |
“” |
Return Values: CallResponse
See CallResponse for more information.